BREAKING CHANGE for 2021.1.1 -> 2021.1.2
Child Job Loop validation of Transformations
Before 2021.1.2, if a childJob task used a loop with a transformation, and that transformation no longer existed on the system, an error would not occur until the childJob task ran. In 2021.1.2, this will now cause a validation error, putting the workflow into draft status and disallowing it from being started.
What should I do?
If an error appears related to missing transformations on a child job loop after saving the workflow or starting a job, it is recommended to update the specified childJob task with a different transformation. Alternatively, this can be fixed by re-importing the transformation, if possible.
Querying outgoing variables for childJob task that has loop properties (POST /workflow_engine/getTask)
Starting in the 2021.1.2 maintenance release, if a childJob task has loop properties set and is queried for using the POST /workflow_engine/getTask API, the returned data structure is changed to return an array of job _ids in the output's loop property. Each _id in the array references the _id of each child job started by the task. This was changed because the outgoing loop data for the childJob task can quickly become too large to handle in the platform. No other APIs were modified but will instead dereference the loop array before returning if the childJob loop task was queried for.
What should I do?
To return the full output of a childJob loop task, you can use the POST /workflow_engine/tasks/search API, which dereferences the data and returns the full output. Otherwise, the data will need to be dereferenced by getting each individual job in the array and querying for the output variables and status.
BREAKING CHANGE for 2021.1.0 -> 2021.1.1
Removal of "progress" key from checkIndexes API
As part of the 2021.1.1 maintenance release, the "progress" key is no longer included as part of the return data from the checkIndexes, or GET /indexes/:collection/status API. The "inProgress" key can be used to determine whether the indexes are currently being created, but the return object no longer includes data about what percentage of the index creation has been completed.
BREAKING CHANGE for 2020.2 -> 2021.1
The following are breaking changes for the 2021.1 release.
API Removal Due to Scheduled Deprecations
The table below shows a list of APIs that have been removed from IAP. Our policy is to provide a deprecation notice two (2) release cycles in advance (at a minimum) before the API is removed.
What should I do?
Review any custom apps and adapters that might reference any APIs on the list and change them to the replacement call (or remove them if no replacement call is given).
Removed APIs
| Item | Description | Deprecation Release | Actual Removal Release | Replacement |
|---|---|---|---|---|
| GET /isAlive | Tool to determine the current status of a service. | 2018.3 | 2021.1 | GET /status |
| restoreDevice | Restore the given configuration to a device. | 2019.1 | 2021.1 | restoreConfig |
Changes to the Pronghorn.getMethods permission for Custom Roles
In 2021.1, the GET /methods/registry API is no longer included in the Pronghorn.getMethods permission for custom roles. Access to the GET /methods/registry API is now included under the Pronghorn.getMethodsRegistry permission instead, and the Pronghorn.getMethods permission solely includes the GET /methods API.
What should I do?
If any custom role contains the Pronghorn.getMethods permission and does not need access to the GET /methods API, please add the new Pronghorn.getMethodsRegistry permission to that role in Authorization Manager.
BREAKING CHANGE for 2020.1 -> 2020.2
The following are breaking changes for the 2020.2 release.
API Removal Due to Scheduled Deprecations
The table below shows a list of APIs that have been removed from IAP. Our policy is to provide a deprecation notice two (2) release cycles in advance (at a minimum) before the API is removed.
Removed APIs
| Item | Description | Deprecation Release | Actual Removal Release | Replacement |
|---|---|---|---|---|
| /mop/ping | Tool to determine the reachability of a device. | N/A | 2020.2 | /configuration_manager/isAlive |
| /importWorkflow | Import a workflow. | 2019.2 | 2020.2 | /workflow_builder/importWorkflow |
| /exportWorkflow | Export a workflow. | 2019.2 | 2020.2 | /workflow_builder/exportWorkflow |
| /queryTasks | Query tasks. | 2019.3 | 2020.2 | /workflow_engine/searchTasks |
| /claimJob | Claim a job. | 2019.3 | 2020.2 | None |
| /releaseJob | Release a job. | 2019.3 | 2020.2 | None |
What should I do?
Review any custom apps and adapters that might reference any APIs on the list and change them to the replacement call (or remove them if no replacement call is given.)
Jade to Pug Update (Custom/Manual Task potentially affected)
Due to security concerns with jade, we have updated to the most recent library named pug. With this change, some custom applications may be affected and need to be tested and updated with a minor adjustment.
What should I do?
Review any custom applications with manual tasks that reference jade and change them to the pug equivalent.
For instance, this code block:
extends ../../../@itential/pronghorn-core/ui/views/layout.jade
block append contentMust be updated to:
extends ../../../@itential/pronghorn-core/ui/views/layout.pug
block append contentOr to this:
extends ../../../@itential/pronghorn-core/ui/views/layout
block append contentAdditionally, any filenames ending in .jade need to be changed to .pug.
Device Broker
| Item | Description | Deprecation Release | Actual Removal Release | Replacement |
|---|---|---|---|---|
| connectDevice | Checks a device connection from Pronghorn (IAP) to a device through NSO. | 2018.3 | 2020.2 | Device Broker isAlive |
| getDeviceGroupsForDevices | Gets the device groups for all devices. | 2018.3 | 2020.2 | Itential no longer supports NSO device groups and auth groups as brokerable constructs. Use adapter tasks instead. |
| liveStatus | Attempts to send data directly to a device. | 2018.3 | 2020.2 | adapter-nso liveStatus |
| liveStatusScanHosts | Will search all hosts that recognize the device. | 2018.3 | 2020.2 | adapter-nso liveStatus |
| syncTo | Syncs the device config to NSO. | 2018.3 | 2020.2 | adapter-nso syncTo |
| updateDeviceSetting | Updates an NSO device setting. | 2018.3 | 2020.2 | adapter-nso addDevice (with settings) |
Service Broker
| Item | Description | Deprecation Release | Actual Removal Release | Replacement |
|---|---|---|---|---|
| dryRunService | Get a dryrun from adding a service instance. | 2018.3 | 2020.2 | None |
| dryRunXML | Dryrun an XML object. | 2018.3 | 2020.2 | adapter-nso dryRunXML |
| fetchData | Performs a search on all currently running NSO instances (set as service types). | 2018.3 | 2020.2 | adapter-nso fetchData |
| findService | Retrieve service data. | 2018.3 | 2020.2 | None |
| getServiceModelMap | Gets all the service models IAP (Itential Automation Platform) currently has access to. | 2018.3 | 2020.2 | adapter-nso getServiceModelMap |
| provisionXML | Provision a service with an XML object. | 2018.3 | 2020.2 | adapter-nso provisionXML |
| runAction | Executes an action on the adapter. | 2018.3 | 2020.2 | adapter-nso runAction |
Removal of Adapter-Mongo
To better support the use of Mongo in the workflow, adapter-mongo was deprecated and removed, and replaced with adapter-db_mongo, an open-sourced adapter. The dbManager is preferred for source code, and adapter-db_mongo is how you access Mongo from a workflow.
As a result of this removal, customers will need to instantiate their database connections for custom applications. Custom applications can continue to use MongoDB, although it is no longer required
- Adapter-mongo is currently instantiating connections by using the MongoDB node.js module in version 3.5.7.
- For your applications to continue working as before, use driver version 3.5.7 to establish a database connection.
- To use MongoDB 3.6 or higher, use the latest version of the MongoDB node driver.
Tags UI Moved to Admin Essentials
The Tags user interface has been removed from its previous location of <base URL>/tags and a new Tags interface has been added to the Admin Essentials home page. Users accessing the previous Tags URI will be redirected to the Admin Essentials home page to access the new Tags interface.
Platform Naming Conventions
All adapters, applications, and brokers must have method parameters and return names that adhere to the new platform naming conventions. For releases in the near future, all non-validating names will cause the adapter, application, or broker to not start in the platform and an error log message will be written to the log files and to standard output (stdout).
The platform naming conventions are also used to validate job variable names in workflows, and any non-validating names will cause the workflow to have errors and be put in "draft" mode. Users cannot start a job from a workflow if it is in "draft" mode.
What should I do?
Consult the documentation explaining the naming conventions. Ensure each job variable defined within all workflows follow the conventions. Use the Level of Effort (LOE) tool to quickly identify any violations to the naming convention.
For any custom applications, adapters, and tasks, review all method parameters and return names to ensure adherence to the naming conventions. Please remember, even though this release will not have any ill-effects and will behave the same as it does in the previous release, future releases will cause these adapters, applications, and tasks to not start.
Return Type Change for getOutOfSyncConfig() in adapter-nso
The getOutOfSyncConfig() function returns a string format configuration containing many out-of-sync configs. However, when a device is in-sync, the function returns an empty array instead of an empty string. This change modifies the return value to an empty string.
BREAKING CHANGE for 2020.1.13 -> 2021.1
createTransformation and updateTransformation API status codes
Upon an upgrade from a 2020.1 maintenance release version before 2020.1.14 to 2021.1, the API status code response for the createTransformation and updateTransformation APIs will now be a 200 instead of a 201 status code upon a successfully created or updated transformation.
What should I do?
Check any custom application which calls the createTransformation or updateTransformation API to see if it uses the statusCode response. If it does, make sure any check for a "201" response instead looks for a "200" response.
BREAKING CHANGE for 2020.1.1 -> 2020.2
RabbitMQ Properties Moved from Service Config to Profile
Upon upgrade from the 2020.1.1 maintenance patch version to the 2020.2 bundle, the RabbitMQ properties will be automatically moved from all service configs to the profile. Additionally, these settings will be changed in the database; therefore all systems that share this database connection will be affected also. Please note, if you have a disaster recovery (DR) system in your setup, the changes made to the database will take effect once the first system is updated and affect all systems using that database. This basically means that all systems will need to be upgraded at the same time.
Rollback Instructions
Since the RabbitMQ properties will be auto-migrated from the service config to the profile, if a rollback is necessary, those properties must be restored manually to each relevant service config prior to upgrade.